docs: add TROUBLESHOOTING.md with 14 common issues - #832
Conversation
Cover SOROBAN_DISABLED mode confusion, CONTRACT_ID format errors, indexer startup failures, SQLite lock errors, and Freighter detection. Link from README.md and CONTRIBUTING.md.
|
@skaichima is attempting to deploy a commit to the ritik4ever's projects Team on Vercel. A member of the Team first needs to authorize it. |
|
@skaichima Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits. You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀 |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughAdds a 305-line troubleshooting guide covering common StellarStream setup and runtime issues, then links it from ChangesTroubleshooting documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
docs/TROUBLESHOOTING.md (1)
23-23: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd language identifiers to fenced code blocks.
markdownlintreports MD040 for these fences. Mark log output astext, shell commands asbash, and configuration snippets asiniso the guide passes documentation linting and renders consistently.Also applies to: 43-43, 61-61, 77-77, 110-110, 134-134, 156-156, 177-177, 206-206, 299-299
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/TROUBLESHOOTING.md` at line 23, Update every fenced code block in TROUBLESHOOTING.md, including the listed locations, with an appropriate language identifier: use text for log output, bash for shell commands, and ini for configuration snippets. Ensure no unlabeled fences remain so markdownlint MD040 passes.Source: Linters/SAST tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/TROUBLESHOOTING.md`:
- Around line 78-79: Update both CONTRACT_ID validation error examples in
TROUBLESHOOTING.md to use the exact emitted STELLAR_CONTRACT_ID messages
asserted by validateEnv.test.ts, including the character-length message, or
explicitly document CONTRACT_ID as an alias while preserving the exact log text.
- Around line 234-240: Update the process-check block in TROUBLESHOOTING.md to
use an Ubuntu/POSIX-compatible command for listing node processes, or explicitly
label the existing Get-Process example as PowerShell and add a separate Linux
command. Ensure the instructions still cover identifying multiple backend
instances and stale processes.
- Around line 142-144: Update the frontend environment setup command in the
troubleshooting documentation so it does not append the literal placeholder as
the contract ID. Use a shell expression that reads the backend CONTRACT_ID
value, or clearly require the developer to replace the placeholder before
execution.
---
Nitpick comments:
In `@docs/TROUBLESHOOTING.md`:
- Line 23: Update every fenced code block in TROUBLESHOOTING.md, including the
listed locations, with an appropriate language identifier: use text for log
output, bash for shell commands, and ini for configuration snippets. Ensure no
unlabeled fences remain so markdownlint MD040 passes.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: e543d145-1722-4fcf-8910-8fab6eea89fd
📒 Files selected for processing (3)
CONTRIBUTING.mdREADME.mddocs/TROUBLESHOOTING.md
| CONTRACT_ID validation failed | ||
| CONTRACT_ID validation issue: must be exactly 56 characters |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Match the documented validation errors to the actual messages.
The supplied tests in backend/src/config/validateEnv.test.ts (Lines 23-71) assert messages containing STELLAR_CONTRACT_ID validation failed, while this guide shows CONTRACT_ID validation failed. Users searching the logs will miss the documented fix path; update both examples to the exact emitted messages or explicitly document the alias.
Also applies to: 111-112
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/TROUBLESHOOTING.md` around lines 78 - 79, Update both CONTRACT_ID
validation error examples in TROUBLESHOOTING.md to use the exact emitted
STELLAR_CONTRACT_ID messages asserted by validateEnv.test.ts, including the
character-length message, or explicitly document CONTRACT_ID as an alias while
preserving the exact log text.
| ```bash | ||
| echo "VITE_CONTRACT_ID=<same value as backend CONTRACT_ID>" >> frontend/.env | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Make the frontend environment command executable as written.
Copying this command verbatim appends the literal value <same value as backend CONTRACT_ID> to frontend/.env, which is not a valid contract ID. Use a shell expression that reads the backend value, or clearly mark the placeholder as something the developer must replace.
Proposed fix
-echo "VITE_CONTRACT_ID=<same value as backend CONTRACT_ID>" >> frontend/.env
+echo "VITE_CONTRACT_ID=$(grep '^CONTRACT_ID=' backend/.env | cut -d= -f2-)" >> frontend/.env📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```bash | |
| echo "VITE_CONTRACT_ID=<same value as backend CONTRACT_ID>" >> frontend/.env | |
| ``` |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/TROUBLESHOOTING.md` around lines 142 - 144, Update the frontend
environment setup command in the troubleshooting documentation so it does not
append the literal placeholder as the contract ID. Use a shell expression that
reads the backend CONTRACT_ID value, or clearly require the developer to replace
the placeholder before execution.
| ```bash | ||
| # Check for multiple backend processes | ||
| Get-Process -Name node -ErrorAction SilentlyContinue | Select-Object Id, StartTime | ||
|
|
||
| # Ensure only one instance is running | ||
| # Kill stale processes if needed | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use an Ubuntu-compatible process check.
The PR objective calls out clean Ubuntu 22.04, but Get-Process is a PowerShell/Windows command and is unavailable in a default Ubuntu shell. Provide a POSIX equivalent or label this block as PowerShell and add a Linux command.
Proposed fix
-Get-Process -Name node -ErrorAction SilentlyContinue | Select-Object Id, StartTime
+pgrep -af node📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```bash | |
| # Check for multiple backend processes | |
| Get-Process -Name node -ErrorAction SilentlyContinue | Select-Object Id, StartTime | |
| # Ensure only one instance is running | |
| # Kill stale processes if needed | |
| ``` |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/TROUBLESHOOTING.md` around lines 234 - 240, Update the process-check
block in TROUBLESHOOTING.md to use an Ubuntu/POSIX-compatible command for
listing node processes, or explicitly label the existing Get-Process example as
PowerShell and add a separate Linux command. Ensure the instructions still cover
identifying multiple backend instances and stale processes.
|
Hi @skaichima, This PR could not be merged because it has merge conflicts with the target branch. Please resolve the merge conflicts, push the updated changes, and the PR can be reviewed and merged. Thank you! |
2 participants
Cover SOROBAN_DISABLED mode confusion, CONTRACT_ID format errors, indexer startup failures, SQLite lock errors, and Freighter detection. Link from README.md and CONTRIBUTING.md.
What changed
Testing done
Related issues
Closes #809
Checklist
Summary by CodeRabbit